Paint Stages

An order in which TImage32 blends layers and bitmap image to its back-buffer is specified by paint stages.

For example, the default sequence of operations includes:

It is possible to change the order in which stages execute at run-time, add new stages, delete old ones, etc., using the PaintStages property of TImage32, which is basically a dynamic indexed list of stages.

TPaintStage Record

Each paint stage is defined with a TPaintStage record:

type TPaintStage = record
  DsgnTime: Boolean;
  RunTime: Boolean;
  Stage: Cardinal; // a PST_* constant
  Parameter: Cardinal; // an optional parameter
end;

where the Stage member holds one of the Paint Stage Constants and defines the action associated with the stage.

All stages include additional parameter, which may be ignored or may be used to store additional stage options. For example, PST_DRAW_LAYERS stage uses its parameter as a 32-bit mask to filter out invisible layers.

By default, TImage32 contains the following stages:

# DsgnTime RunTime Stage Parameter
0 True True PST_CLEAR_BACKGND not used
1 False True PST_CONTROL_FRAME not used
2 True True PST_DRAW_BITMAP not used
3 False True PST_BITMAP_FRAME not used
4 True True PST_DRAW_LAYERS $80000000

See 'Using Layers' for an explanation of the parameter value in PST_DRAW_LAYERS stage.

Customizing TImage32 at Run-Time

A PST_CUSTOM stage deserves a little bit deeper explanation. It causes the control to issue an OnPaintStage event, thus allowing to change TImage32 behavior at run-time.

The OnPaintStage event is of a TPaintStageEvent type:

type TPaintStageEvent = procedure(Sender: TObject; Dest: TBitmap32; StageNum: Cardinal) of object;

In the event handler, the application can perform some custom operations over the back-buffer of the control.

Note, that by default, TImage32 does not generate OnPaintStage. In order to make it do so, you have to insert a new stage in the PaintStages list, and set its Stage to PST_CUSTOM, or change one of the existing stages, for example:

type

  TForm1 = class(TForm)

    Image32: TImage32;

    procedure Image32InitStages(Sender: TObject); // OnInitStages

    procedure Image32PaintStage(Sender: TObject; Dest: TBitmap32; StageNum: Cardinal); // OnPaintStage

  private

    { Private declarations }

  public

    { Public declarations }

  end;

 

var

  Form1: TForm1;

 

implementation

 

{$R *.DFM}


procedure TForm1.Image32InitStages(Sender: TObject);

begin

  // change default PST_CLEAR_BACKGND (0-th stage) to a custom handler

  with Image32.PaintStages[0] do

  begin

    Stage := PST_CUSTOM;

    Parameter := 1; // use parameter to tag the stage

  end;

 

  // insert another custom stage after the bitmap image

  // was drawn, but before the control starts painting layers

  with Image32.PaintStages.Insert(4) do

  begin

    // Note that for new stages RunTime = True by default

    Stage := PST_CUSTOM;

    Paramteter := 2; // use parameter to tag the stage

  end;

end ;

 

procedure TForm1.Image32PaintStage(Sender: TObject; Dest: TBitmap32; StageNum: Cardinal);

begin

  // OnPaintStage Handler

  case Image32.PaintStages[StageNum].Parameter of

    1: // do something with the background

    2: // call another handler

  end;

end;

GDI Overlays

[ Note: Most likely GDI Overlays will not be used in future versions. Do not use them ]

A final step in TImage32 repainting is the drawing of GDI overlays. This operation is performed after the bitmap image and layers have been combined in a back buffer and copied to the screen canvas.

At this stage, TImage32 fires the OnGDIOverlay event, where you can perform drawing using the standard Canvas of the TImage32.

The main reason for introducing this stage is that painting of GDI overlays does not affect the contents of the buffer, that is changes in overlay image will not cause buffer invalidation. However, GDI overlays have to be repainted each time the control repaints itself, and they are not flicker-free.

See Also

Using Layers, TCustomImage32.OnGDIOverlay, TCustomImage32.OnPaintStage, TCustomImage32.PaintStages, Paint Stage Constants, TPaintStage